<html>
  <head>
<!--   
   Copyright 1999-2004 The Apache Sofware Foundation.
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
    <title>The servlet engine implementation</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  </head>
  
  <body bgcolor="#FFFFFF">
    <h2>Architecture</h2>
    
    <p>Tomcat core defines a number of base abstractions ( Request, Response,
    Context, etc ) and a simple interface for modules.</p>

    <p>All server functionality is implemented in modules, using callbacks in
      a model similar with Apache and other servers. </p>

    <p>The ServletAPI and all specific contracts are implemented in 
      special module(s) - that allows to keep the core simple and 
      permits more flexibility. </p>
    
    <p>The callbacks are defined in BaseInterceptor. A module will 
      extend that class and possibly Handler if it wants to generate
      content. The module will use the information and API provided in Request,
      Response, Context, Container.

    <h2>Components</h2>

    <dl>

      <dt>ContextManager</dt>
      <dd>
    	<ul>
      	  <li>control point for callback calls and notifications.</li>
      	  <li>manages server startup/shudown</li>
      	  <li>manages request execution (entry point,coordinates modules)</li>
      	  <li>maintains a list of global modules</li>
      	  <li>maintains a list of webapps</li>
    	</ul>
      </dd>
      
      <dt>Request,Response</dt>
      <dd>Internal representations for HTTP request/response, including 
	common attributes. Tuned for memory use ( recycling ) and performance,
	with minimal contracts.
      </dd>

      <dt>Module base ( BaseInterceptor )</dt>
      <dd> 
	An interceptor defines callbacks ( or hooks ) that implement one or
	several server functions. Almost all of the processing logic is
	implemented as interceptor callbacks. 
      </dd>

      <dt>Handler</dt>
      <dd>
    	Content generator part of modules. Simple generators ( like 
	error handlers), wrappers for Servlets or JSPs or complex 
	chains/pipelines can be implemented. The handlers are defined
	as part of modules.
      </dd>
      
      <dt>Context</dt>
      <dd>Attributes shared by a web application, included local modules. 
      </dd>

      <dt>Container</dt>
      <dd>
    	Attributes shared by a group of URLs ( mappings, modules, 
	authentication ). This is also the repository for modules used by
	ContextManager and Context ( which delegate to the "default"
	container ). The default container for the ContextManager stores
	attributes common to all URLs ( global modules, etc ), same 
	for Context.
      </dd>
      
      <dt>ServerSession</dt>
      <dd>Server view of a session - independent of the actual implementation
	of the session manager. Modules implementing the session management
	callbacks may use a subclass and manage the sessions/
      </dd>

      <dt>OutputBuffer</dt>
      <dd>All content is stored in the OutputBuffer, which implement
	storage and conversion functions ( with a lot of tunning for
	performance and memory usage )
      </dd>

    </dl>

    <h2>Dependencies</h2>

    <ul>
       <li>org.apache.tomcat.util.log.Log</li>
       <li>org.apache.tomcat.util.hooks.Hooks</li>
       <li>org.apache.tomcat.util.http.*</li>
       <li>org.apache.tomcat.util.res.StringManager</li>
       <li>org.apache.tomcat.util.buf.MessageBytes;</li>
    </ul>

    Indirect dependencies:
    <ul>
      <li>FastDateFormat, collections.Queue ( Log implementation )</li>
      <li>collections.MultipMap ( http )

    </ul>

    <h2>Sandboxing</h2>
    
    Tomcat core and the associated utils can be sandboxed. In order to operate,
    it'll need the following permissions:

   <h2>JDK support</h2>
   
   Tomcat core and the utilities it depends on are JDK1.1 compatible. 

   <p>Modules may require JDK1.2 or special APIs, but it is allways possible
     to use a more limited version that works on JDK1.1. Most modules
     that are distributed with tomcat are JDK1.1 compatible ( but they
     can take advantage of JDK1.2 features if detected ).</p>
   
   <h2>Notes</h2>

   <p>Modules may store various "notes" ( the name is from apache ). Notes are 
   internal attributes, and can be accessed by name and by index ( to 
   avoid hashtable lookups in the critical path ).<p>

   <p>Notes are used for attribute-specific informations, and are a mechanism
     to share information between related modules.</p>

   <p>The following notes are known defined:</p> 
   <!-- XXX move this in the modules documentation - the core doesn't care -->

   <ul>
     <li>configFile - CM - ServerXmlReader - location of server.xml </li>
     <li></li>
     <li></li>
   </ul>
    
  </body>
</html>
